package com.siashan.toolkit.crypt.binary;

import com.siashan.toolkit.crypt.*;
import com.siashan.toolkit.crypt.util.StringUtils;

import java.util.Arrays;
import java.util.Objects;

/**
 * Base 算法抽象类
 *
 * @author siashan
 * @since v1.0.7
 */
public abstract class BaseNCodec implements BinaryEncoder, BinaryDecoder {

    /**
     * 保存线程上下文，因此类可以是线程安全的
     *
     * 这个类本身不是线程安全的；每个线程必须分配自己的副本.
     *
     * @since 1.0.7
     */
    static class Context {

        /**
         * 我们正在处理的基于逻辑的字节的占位符.
         * 按位操作存储并提取此变量的编码或解码.
         */
        int ibitWorkArea;

        /**
         * 我们正在处理的基于逻辑的字节的占位符.
         * 按位操作存储并提取此变量的编码或解码.
         */
        long lbitWorkArea;

        /**
         * 流媒体缓冲区.
         */
        byte[] buffer;

        /**
         * 应在缓冲区中写入下一个字符的位置.
         */
        int pos;

        /**
         * 从缓冲区读取下一个字符的位置.
         */
        int readPos;

        /**
         * 表示已达到EOF的布尔标志。一旦达到EOF，该对象将变得无用,必须扔掉
         */
        boolean eof;

        /**
         * 变量跟踪已写入当前行的字符数。仅在编码时使用。我们使用
         * 它可以确保每一个编码的行永远不会超过lineLength（如果lineLength&gt；0）
         */
        int currentLinePos;

        /**
         * 只有在编码时每读取3/5次，解码时每读取4/8次后，才会写入缓冲区。这变量有助于跟踪它。
         */
        int modulus;

        Context() {
        }

        /**
         * 返回对调试有用的字符串（特别是在调试器中）
         *
         * @return 用于调试的字符串。
         */
        @SuppressWarnings("boxing") // OK to ignore boxing here
        @Override
        public String toString() {
            return String.format("%s[buffer=%s, currentLinePos=%s, eof=%s, ibitWorkArea=%s, lbitWorkArea=%s, " +
                    "modulus=%s, pos=%s, readPos=%s]", this.getClass().getSimpleName(), Arrays.toString(buffer),
                    currentLinePos, eof, ibitWorkArea, lbitWorkArea, modulus, pos, readPos);
        }
    }

    /**
     * EOF
     *
     * @since 1.0.7
     */
    static final int EOF = -1;

    /**
     *  根据RFC 2045第6.8节的MIME块大小
     *
     * <p>
     * {@value}字符限制不计算尾随的CRLF，但计算所有其他字符，包括任何字符等号。
     * </p>
     *
     * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045 section 6.8</a>
     */
    public static final int MIME_CHUNK_SIZE = 76;

    /**
     * 根据RFC 1421第4.3.2.4节，PEM块大小.
     *
     * <p>
     * {@value}字符限制不计算尾随的CRLF，但计算所有其他字符，包括任何等号
     * </p>
     *
     * @see <a href="http://tools.ietf.org/html/rfc1421">RFC 1421 section 4.3.2.4</a>
     */
    public static final int PEM_CHUNK_SIZE = 64;

    private static final int DEFAULT_BUFFER_RESIZE_FACTOR = 2;

    /**
     * 定义默认缓冲区大小-当前为{@value}
     * -必须足够大，以容纳至少一个编码块+分隔符
     */
    private static final int DEFAULT_BUFFER_SIZE = 8192;

    /**
     * 要分配的最大缓冲区大小.
     *
     * <p>这与JDK{@code java.util.ArrayList}中使用的大小相同:</p>
     * <blockquote>
     * 有些虚拟机在数组中保留一些头字。
     * 尝试分配较大的阵列可能会导致
     * OutOfMemoryError:请求的数组大小超过VM限制。
     * </blockquote>
     */
    private static final int MAX_BUFFER_SIZE = Integer.MAX_VALUE - 8;

    /** 用于提取8位的掩码，用于解码字节 */
    protected static final int MASK_8BITS = 0xff;

    /**
     * 用于填充输出的字节.
     */
    protected static final byte PAD_DEFAULT = '='; // Allow static access to default

    /**
     * 默认解码策略.
     */
    protected static final CodecPolicy DECODING_POLICY_DEFAULT = CodecPolicy.LENIENT;

    /**
     * 符合RFC 2045第2.1节的区块分隔符.
     *
     * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045 section 2.1</a>
     */
    static final byte[] CHUNK_SEPARATOR = {'\r', '\n'};

    /**
     * 比较两个{@code int}值，并对这些值进行数值处理没有签名。摘自JDK1.8
     *
     *
     * @param  x 要比较的第一个{@code int}
     * @param  y 要比较的第二个{@code int}
     * @return 如果{@code x==y}，则值{@code 0}；没有价值
     *          如果{@code x<y}作为无符号值，则大于{@code 0}；和
     *          如果{@code x>y}为，则大于{@code 0}的值
     *          无符号值
     */
    private static int compareUnsigned(final int x, final int y) {
        return Integer.compare(x + Integer.MIN_VALUE, y + Integer.MIN_VALUE);
    }

    /**
     * 创建至少与最小所需容量相同的正容量。
     * 如果最小容量为负，则会抛出OutOfMemoryError，因为没有数组
     * 可以分配.
     *
     * @param minCapacity 最小容量
     * @return 容量
     * @throws OutOfMemoryError 如果{@code minCapacity}为负
     */
    private static int createPositiveCapacity(final int minCapacity) {
        if (minCapacity < 0) {
            // overflow
            throw new OutOfMemoryError("Unable to allocate array size: " + (minCapacity & 0xffffffffL));
        }
        // This is called when we require buffer expansion to a very big array.
        // Use the conservative maximum buffer size if possible, otherwise the biggest required.
        //
        // Note: In this situation JDK 1.8 java.util.ArrayList returns Integer.MAX_VALUE.
        // This excludes some VMs that can exceed MAX_BUFFER_SIZE but not allocate a full
        // Integer.MAX_VALUE length array.
        // The result is that we may have to allocate an array of this size more than once if
        // the capacity must be expanded again.
        return (minCapacity > MAX_BUFFER_SIZE) ?
            minCapacity :
            MAX_BUFFER_SIZE;
    }

    /**
     * 根据RFC 2045第2.1节获取块分隔符的副本.
     *
     * @return 块分隔符
     * @see <a href="http://www.ietf.org/rfc/rfc2045.txt">RFC 2045 section 2.1</a>
     * @since 1.0.7
     */
    public static byte[] getChunkSeparator() {
        return CHUNK_SEPARATOR.clone();
    }

    /**
     * 检查字节值是否为空白.
     * 空格的意思是：空格、制表符、CR、LF
     * @param byteToCheck
     *            要检查的字节
     * @return 如果字节为空白，则为true，否则为false
     */
    protected static boolean isWhiteSpace(final byte byteToCheck) {
        switch (byteToCheck) {
            case ' ' :
            case '\n' :
            case '\r' :
            case '\t' :
                return true;
            default :
                return false;
        }
    }

    /**
     * 通过 {@link #DEFAULT_BUFFER_RESIZE_FACTOR} 增加缓冲区.
     * @param context 要使用的上下文
     * @param minCapacity 所需的最小容量
     * @return 调整大小的字节[]缓冲区
     * @throws OutOfMemoryError 如果{@code minCapacity}为负
     */
    private static byte[] resizeBuffer(final Context context, final int minCapacity) {
        // Overflow-conscious code treats the min and new capacity as unsigned.
        final int oldCapacity = context.buffer.length;
        int newCapacity = oldCapacity * DEFAULT_BUFFER_RESIZE_FACTOR;
        if (compareUnsigned(newCapacity, minCapacity) < 0) {
            newCapacity = minCapacity;
        }
        if (compareUnsigned(newCapacity, MAX_BUFFER_SIZE) > 0) {
            newCapacity = createPositiveCapacity(minCapacity);
        }

        final byte[] b = new byte[newCapacity];
        System.arraycopy(context.buffer, 0, b, 0, context.buffer.length);
        context.buffer = b;
        return b;
    }

    // 实例变量，以防以后需要更改
    protected final byte pad;

    /** 每个完整的未编码数据块中的字节数，例如，Base64为4，Base32为5 */
    private final int unencodedBlockSize;

    /** 每个完整编码数据块中的字节数，例如，Base64为3，Base32为8 */
    private final int encodedBlockSize;

    /**
     * 用于编码的块大小。解码时不使用.
     * 值为零或更小意味着编码数据不分块.
     * 向下舍入到encodedBlockSize的最近倍数.
     */
    protected final int lineLength;

    /**
     * 块分隔符的大小。除非{@link#lineLength}&gt；0.
     */
    private final int chunkSeparatorLength;

    /**
     * 定义输入字节包含剩余尾随位时的解码行为
     * 无法使用有效的编码创建。这些可以是从最终版本中未使用的位
     * 字符或整个字符。默认模式是宽松解码。将此设置为
     * {@code true}以启用严格解码。
     * <ul>
     * <li>宽松：在可能的情况下，任何尾随位都被组成8位字节。其余部分将被丢弃.
     * <li>严格：解码将引发{@link IllegalArgumentException}如果尾随位
     * 不是有效编码的一部分。最后一个字符中任何未使用的位必须
     * 是零。不允许对整个最终字符进行不可能计数.
     * </ul>
     *
     * <p>当启用严格解码时，预计解码的字节将被重新编码
     * 与原始数组相匹配的字节数组，即最终数组没有变化
     * 性格这要求输入字节使用相同的填充和字母表
     * 作为编码器。
     * </p>
     */
    private final CodecPolicy decodingPolicy;

    /**
     * 注{@code lineLength}向下舍入到编码块大小的最近倍数。
     * 如果{@code chunkSeparatorLength}为零，则禁用分块。
     * @param unencodedBlockSize 未编码块的大小（例如Base64=3）
     * @param encodedBlockSize 编码块的大小（例如Base64=4）
     * @param lineLength 如果&gt；0，使用长度为{@code lineLength}的分块
     * @param chunkSeparatorLength 块分隔符长度（如果相关）
     */
    protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize,
                         final int lineLength, final int chunkSeparatorLength) {
        this(unencodedBlockSize, encodedBlockSize, lineLength, chunkSeparatorLength, PAD_DEFAULT);
    }

    /**
     * 注{@code lineLength}向下舍入到编码块大小的最近倍数。
     * 如果{@code chunkSeparatorLength}为零，则禁用分块。
     * @param unencodedBlockSize 未编码块的大小（例如Base64=3）
     * @param encodedBlockSize 编码块的大小（例如Base64=4）
     * @param lineLength 如果&gt；0，使用长度为{@code lineLength}的分块
     * @param chunkSeparatorLength 块分隔符长度（如果相关）
     * @param pad 用作填充字节的字节.
     */
    protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize,
                         final int lineLength, final int chunkSeparatorLength, final byte pad) {
        this(unencodedBlockSize, encodedBlockSize, lineLength, chunkSeparatorLength, pad, DECODING_POLICY_DEFAULT);
    }

    /**
     * 注{@code lineLength}向下舍入到编码块大小的最近倍数。
     * 如果{@code chunkSeparatorLength}为零，则禁用分块.
     * @param unencodedBlockSize 未编码块的大小（例如Base64=3）
     * @param encodedBlockSize 编码块的大小（例如Base64=4）
     * @param lineLength 如果&gt；0，使用长度为{@code lineLength}的分块
     * @param chunkSeparatorLength 块分隔符长度（如果相关）
     * @param pad 用作填充字节的字节.
     * @param decodingPolicy 解码策略.
     * @since 1.0.7
     */
    protected BaseNCodec(final int unencodedBlockSize, final int encodedBlockSize,
                         final int lineLength, final int chunkSeparatorLength, final byte pad, final CodecPolicy decodingPolicy) {
        this.unencodedBlockSize = unencodedBlockSize;
        this.encodedBlockSize = encodedBlockSize;
        final boolean useChunking = lineLength > 0 && chunkSeparatorLength > 0;
        this.lineLength = useChunking ? (lineLength / encodedBlockSize) * encodedBlockSize : 0;
        this.chunkSeparatorLength = chunkSeparatorLength;
        this.pad = pad;
        this.decodingPolicy = Objects.requireNonNull(decodingPolicy, "codecPolicy");
    }

    /**
     * 返回可用于读取的缓冲数据量.
     *
     * @param context 要使用的上下文
     * @return 可用于读取的缓冲数据量.
     */
    int available(final Context context) {  // package protected for access from I/O streams
        return context.buffer != null ? context.pos - context.readPos : 0;
    }

    /**
     * 测试给定的字节数组，查看它是否包含字母表或键盘中的任何字符.
     *
     * 用于检查行尾数组
     *
     * @param arrayOctet
     *            要测试的字节数组
     * @return {@code true}如果任何字节是字母表或键盘中的有效字符；{@code false}否则
     */
    protected boolean containsAlphabetOrPad(final byte[] arrayOctet) {
        if (arrayOctet == null) {
            return false;
        }
        for (final byte element : arrayOctet) {
            if (pad == element || isInAlphabet(element)) {
                return true;
            }
        }
        return false;
    }

    /**
     * 解码包含Base-N字母表中字符的字节[].
     *
     * @param pArray
     *            一种包含基N字符数据的字节数组
     * @return 包含二进制数据的字节数组
     */
    @Override
    public byte[] decode(final byte[] pArray) {
        if (pArray == null || pArray.length == 0) {
            return pArray;
        }
        final Context context = new Context();
        decode(pArray, 0, pArray.length, context);
        decode(pArray, 0, EOF, context); // Notify decoder of EOF.
        final byte[] result = new byte[context.pos];
        readResults(result, 0, result.length, context);
        return result;
    }

    // package protected for access from I/O streams
    abstract void decode(byte[] pArray, int i, int length, Context context);

    /**
     * 使用Base-N算法解码对象。提供此方法是为了满足
     * 解码器接口，如果提供的对象不是byte[]或String类型，则将抛出DecoderException
     *
     * @param obj
     *            要解码的对象
     * @return 一个对象（类型为byte[]），包含对应于byte[]或字符串的二进制数据提供.
     * @throws DecoderException
     *             如果提供的参数不是byte[]类型
     */
    @Override
    public Object decode(final Object obj) throws DecoderException {
        if (obj instanceof byte[]) {
            return decode((byte[]) obj);
        } else if (obj instanceof String) {
            return decode((String) obj);
        } else {
            throw new DecoderException("Parameter supplied to Base-N decode is not a byte[] or a String");
        }
    }

    /**
     * 解码包含Base-N字母表中字符的字符串.
     *
     * @param pArray
     *            包含以N为基数的字符数据的字符串
     * @return 包含二进制数据的字节数组
     */
    public byte[] decode(final String pArray) {
        return decode(StringUtils.getBytesUtf8(pArray));
    }

    /**
     * 将包含二进制数据的字节[]编码为包含字母表中字符的字节[].
     *
     * @param pArray
     *            包含二进制数据的字节数组
     * @return 仅包含基N字母字符数据的字节数组
     */
    @Override
    public byte[] encode(final byte[] pArray) {
        if (pArray == null || pArray.length == 0) {
            return pArray;
        }
        return encode(pArray, 0, pArray.length);
    }

    /**
     * 将包含二进制数据的字节[]编码为包含二进制数据的字节[]
     * 字母表中的字符.
     *
     * @param pArray
     *            包含二进制数据的字节数组
     * @param offset
     *            子阵列的初始偏移量。
     * @param length
     *            子阵列的长度。
     * @return 仅包含基N字母字符数据的字节数组
     */
    public byte[] encode(final byte[] pArray, final int offset, final int length) {
        if (pArray == null || pArray.length == 0) {
            return pArray;
        }
        final Context context = new Context();
        encode(pArray, offset, length, context);
        encode(pArray, offset, EOF, context); // Notify encoder of EOF.
        final byte[] buf = new byte[context.pos - context.readPos];
        readResults(buf, 0, buf.length, context);
        return buf;
    }

    // package protected for access from I/O streams
    abstract void encode(byte[] pArray, int i, int length, Context context);

    /**
     * 使用Base-N算法对对象进行编码。提供此方法是为了满足
     * 编码器接口，如果提供的对象不是byte[]类型，则将抛出EncoderException.
     *
     * @param obj
     *            对象进行编码
     * @return 一个对象（类型为byte[]），包含与提供的byte[]相对应的Base-N编码数据.
     * @throws EncoderException
     *             如果提供的参数不是byte[]类型
     */
    @Override
    public Object encode(final Object obj) throws EncoderException {
        if (!(obj instanceof byte[])) {
            throw new EncoderException("Parameter supplied to Base-N encode is not a byte[]");
        }
        return encode((byte[]) obj);
    }

    /**
     * 将包含二进制数据的字节[]编码为包含相应字母表中字符的字符串.
     * UTF使用8编码.
     *
     * @param pArray 包含二进制数据的字节数组
     * @return 仅包含相应字母表中的字符数据的字符串.
    */
    public String encodeAsString(final byte[] pArray){
        return StringUtils.newStringUtf8(encode(pArray));
    }

    /**
     * 将包含二进制数据的字节[]编码为包含Base-N字母表中字符的字符串。
     * 使用 UTF8 编码.
     *
     * @param pArray
     *            包含二进制数据的字节数组
     * @return 仅包含基N字符数据的字符串
     */
    public String encodeToString(final byte[] pArray) {
        return StringUtils.newStringUtf8(encode(pArray));
    }

    /**
     * 确保缓冲区有空间容纳{@code size}字节
     *
     * @param size 所需的最小备用空间
     * @param context 要使用的上下文
     * @return 缓冲区
     */
    protected byte[] ensureBufferSize(final int size, final Context context){
        if (context.buffer == null) {
            context.buffer = new byte[Math.max(size, getDefaultBufferSize())];
            context.pos = 0;
            context.readPos = 0;

            // Overflow-conscious:
            // x + y > z  ==  x + y - z > 0
        } else if (context.pos + size - context.buffer.length > 0) {
            return resizeBuffer(context, context.pos + size);
        }
        return context.buffer;
    }

    /**
     * 返回解码行为策略.
     * 
     * <p>
     * 默认为宽松。如果解码策略是严格的，则解码将引发错误
     * {@link IllegalArgumentException}如果尾随位不是有效编码的一部分。解码将组成
     * 将尾随位转换为8位字节，并丢弃剩余的字节.
     * </p>
     *
     * @return 如果使用严格解码，则为true
     */
    public CodecPolicy getCodecPolicy() {
        return decodingPolicy;
    }

    /**
     * 获取默认缓冲区大小。可以覆盖.
     *
     * @return 默认缓冲区大小.
     */
    protected int getDefaultBufferSize() {
        return DEFAULT_BUFFER_SIZE;
    }

    /**
     * 计算对提供的数组进行编码所需的空间量.
     *
     * @param pArray 字节[]数组，稍后将对其进行编码
     *
     * @return 对提供的数组进行编码所需的空间量.
     */
    public long getEncodedLength(final byte[] pArray) {
        // Calculate non-chunked size - rounded up to allow for padding
        // cast to long is needed to avoid possibility of overflow
        long len = ((pArray.length + unencodedBlockSize-1)  / unencodedBlockSize) * (long) encodedBlockSize;
        if (lineLength > 0) { // We're using chunking
            // Round up to nearest multiple
            len += ((len + lineLength-1) / lineLength) * chunkSeparatorLength;
        }
        return len;
    }

    /**
     * 如果此对象具有用于读取的缓冲数据，则返回true.
     *
     * @param context 要使用的上下文
     * @return 如果仍有数据可供读取，则为true.
     */
    boolean hasData(final Context context) {  // package protected for access from I/O streams
        return context.buffer != null;
    }

    /**
     * 返回{@code octet}是否在当前字母表中.
     * 不允许空白或填充.
     *
     * @param value 要测试的值
     *
     * @return {@code true}如果值是在当前字母表中定义的，则{@code false}否则.
     */
    protected abstract boolean isInAlphabet(byte value);

    /**
     * 测试给定的字节数组，看它是否只包含字母表中的有效字符.
     * 该方法选择性地将空格和pad视为有效.
     *
     * @param arrayOctet 要测试的字节数组
     * @param allowWSPad 如果{@code true}，则也允许使用空格和PAD
     *
     * @return {@code true}如果所有字节都是字母表中的有效字符，或者如果字节数组为空；否则为{@code false}
     */
    public boolean isInAlphabet(final byte[] arrayOctet, final boolean allowWSPad) {
        for (final byte octet : arrayOctet) {
            if (!isInAlphabet(octet) &&
                    (!allowWSPad || (octet != pad) && !isWhiteSpace(octet))) {
                return false;
            }
        }
        return true;
    }

    /**
     * 测试给定字符串，查看其是否仅包含字母表中的有效字符.
     * 该方法将空格和PAD视为有效.
     *
     * @param basen 要测试的字符串
     * @return {@code true}如果字符串中的所有字符都是字母表中的有效字符，或者
     *          字符串为空；{@code false}，否则为
     * @see #isInAlphabet(byte[], boolean)
     */
    public boolean isInAlphabet(final String basen) {
        return isInAlphabet(StringUtils.getBytesUtf8(basen), true);
    }

    /**
     * 如果解码行为严格，则返回true。如果出现拖尾，解码将引发{@link IllegalArgumentException}
     * 位不是有效编码的一部分.
     *
     * <p>
     * 对于宽松解码，默认值为false。解码将把尾随位合成8位字节，并丢弃余数
     * </p>
     *
     * @return 如果使用严格解码，则为true
     */
    public boolean isStrictDecoding() {
        return decodingPolicy == CodecPolicy.STRICT;
    }

    /**
     * 将缓冲数据提取到提供的byte[]数组中，从位置bPos开始，最大值为bAvail字节。返回实际提取的字节数。
     * <p>
     * 受保护的包，可从I/O流访问.
     *
     * @param b
     *            字节[]数组，用于将缓冲数据提取到.
     * @param bPos
     *            在字节[]数组中开始提取的位置.
     * @param bAvail
     *            允许提取的字节数。我们可能提取较少的（如果可用较少）.
     * @param context
     *            要使用的上下文
     * @return 成功提取到提供的字节[]数组中的字节数.
     */
    int readResults(final byte[] b, final int bPos, final int bAvail, final Context context) {
        if (context.buffer != null) {
            final int len = Math.min(available(context), bAvail);
            System.arraycopy(context.buffer, context.readPos, b, bPos, len);
            context.readPos += len;
            if (context.readPos >= context.pos) {
                context.buffer = null; // so hasData() will return false, and this method can return -1
            }
            return len;
        }
        return context.eof ? EOF : 0;
    }
}
